BOLT 4 - onion routing protocol

2022-03-17 ยท 2 min read

Source: https://github.com/lightning/bolts/blob/master/04-onion-routing.md

Terminology #

  • Origin Node
  • Intermediate Node, a.k.a. Hop
  • Final Node
  • Route: list of Hops, constructed by Origin Node

Overview #

  • Route payment HTLC from origin node to final node via many intermediate nodes.
  • Based on (2009) Sphinx - A Compact and Provably Secure Mix Format (co-authored by old colleague George Danezis :)), extended with a per-hop payload.
  • Intermediate nodes can't learn (1) origin, (2) other hops (except pred- and succ- hops), (3) route length, or (4) position in route.
  • Origin node must pre-compute full route. Must learn pubkey of each intermediate (and final) node.
  • Intermediate nodes advertise their fee schema.
    • Fees are just (flat base rate + proportional rate).
    • If nodes advertise new fee rates, they must continue to accept their stale fee rates for a little while longer to account for propagation delay.
  • Origin node also effectively decides the fee each hop will pay. If an intermediate node deviates (forwards less than advertised) then subsequent nodes must reject.
  • Each hop sees a hop payload consisting of
    • (1) amount to forward: u64
    • (2) outgoing cltv value: u32
    • (3) short channel id
    • (4) payment data: (payment secret, total msat)
    • (5): payment metadata: bytes